Add researcher guide and fair usage policy as new data-access docs section by Baalmart · Pull Request #3609 · airqo-platform/AirQo-frontend

Baalmart · 2026-06-09T19:43:34Z

🚀 Pull Request

📋 Description

What does this PR do?

Introduces a new top-level data-access/ section in the docs-website with two comprehensive guides migrated from internal Word documents:

data-access/researchers-guide.md — Full data access guide for academic and scientific researchers: calibration methodology, temporal/spatial aggregation, data quality thresholds, network specs, field deployment guidance, WHO reference levels, FAQ, terms of use, and a quick-reference checklist appendix.
data-access/fair-usage-policy.md — Fair usage policy covering the rationale for the 3-month batch download limit, batch download workflows, API rate limiting principles, fair usage principles table, and data quality/completeness guidance.
sidebars.ts — New dataAccessSidebar entry added, autogenerated from data-access/.

Why is this change needed?

Both documents previously existed only as internal Word files shared on request. Migrating them into the docs-website makes them:

Discoverable — linked from within the API docs and findable via search.
Self-contained — the retiring docs.airqo.net external link referenced in these guides is replaced with internal links to ../api/intro.md.
Maintainable — version-controlled alongside the rest of the product documentation.

The data-access/ top-level placement (rather than inside api/ or analytics/) reflects that both guides apply across multiple AirQo products (Analytics Platform, API, and Mobile App).

🔗 Related Issues

Closes #
Fixes #
Related to #

🔄 Type of Change

🏗️ Affected Services

Microservices changed: N/A — documentation only.

🧪 Testing

Unit tests added/updated
Manual testing completed
All existing tests pass

Test summary:
Verified Docusaurus build passes with no broken-link errors. Confirmed that cross-links between the two new pages (./fair-usage-policy.md ↔ ./researchers-guide.md) and from the new pages to the API intro (../api/intro.md) all resolve correctly. The retiring docs.airqo.net URL has been replaced with the internal API link throughout both files.

💥 Breaking Changes

No breaking changes
Has breaking changes (describe below)

📝 Additional Notes

The dataAccessSidebar is autogenerated, so adding further guides under docs/data-access/ in future PRs requires no sidebar config changes.
Both documents retain their original version numbers and dates from the source Word files (Researchers Guide v1.0.3 April 2026; Fair Usage Policy v1.0 January 2026).
External links to the Analytics Platform, network coverage page, and calibration methodology paper are intentionally kept as external URLs since they point to the main AirQo website, not the docs-website.

✅ Checklist

Code follows project style guidelines
Self-review completed
Documentation updated (if needed)
Ready for review

Summary by CodeRabbit

Documentation

Added Fair Usage Policy documentation defining download caps, API access details, fair usage principles, rate limits, support guidance, and prohibited uses
Added Researchers Guide with comprehensive end-to-end guidance on accessing and using air quality data, including calibration methodology, access channels, and best practices
Updated documentation website with new data-access section

…ction

coderabbitai · 2026-06-09T19:46:12Z

Warning

Review limit reached

@Baalmart, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 47 minutes and 45 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 40fa5aec-c457-45d8-abe5-1214d258c0c5

📥 Commits

Reviewing files that changed from the base of the PR and between bdaab28 and 47aab8f.

📒 Files selected for processing (2)

src/docs-website/docs/data-access/fair-usage-policy.md
src/docs-website/docs/data-access/researchers-guide.md

📝 Walkthrough

Walkthrough

This PR introduces comprehensive data access documentation for the AirQo platform: a fair usage policy defining download caps and operational constraints, a researchers guide providing end-to-end methodology and best practices for data access and analysis, and updated sidebar navigation for Docusaurus discoverability.

Changes

Data Access Documentation & Navigation

Layer / File(s)	Summary
Fair Usage Policy `src/docs-website/docs/data-access/fair-usage-policy.md`	Defines explicit ~3-month per-query download limit, batch workflows via Analytics Platform and API, fair-usage principles (batching, tool selection, calibrated data, local storage), prohibited behaviors (excessive exports, unbounded automation, staff workarounds), data quality thresholds (≥50% completeness), missing-data handling, coordinate privacy policy, and support details.
Researchers Guide - Foundation & Methodology `src/docs-website/docs/data-access/researchers-guide.md`	Document introduction, frontmatter, and core methodology sections covering open-access principles with batch limits, calibration approaches (raw vs. calibrated), temporal/frequency guidance (sampling rates, aggregation, completeness thresholds, missing-data policy), and spatial guidance (coordinate approximation, monitor selection, city-level aggregation).
Researchers Guide - Access Channels & Technical Operations `src/docs-website/docs/data-access/researchers-guide.md`	Network overview (size, coverage, monitor types, uptime/lifespan), access channels (mobile app, analytics platform, REST API with tiered pricing), data quality/accuracy scope (calibration signals, intended uses, meteorological limitations), and technical network specifications (hardware, sampling frequency, power, connectivity, deployment, maintenance).
Researchers Guide - Field Practices, Best Practices & Support `src/docs-website/docs/data-access/researchers-guide.md`	Field deployment and calibration guidance (co-location intervals, remote correction, sensor relocation, reference-grade requirements), researcher best practices (download/processing, spatial/temporal analysis, reporting/citation), WHO air quality guideline reference, FAQ (data availability, coordinates, raw data, outliers, health suitability, download limits), collaboration opportunities, support/contact details, terms of use, and quick-reference checklist.
Documentation Site Navigation `src/docs-website/sidebars.ts`	Docusaurus sidebar configuration updated to include `dataAccessSidebar` with autogenerated `data-access` directory for site navigation.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

📚 Fair usage takes the stage today,
researchers find their methodical way—
from calibration calls to coordinate care,
batched downloads prove we truly share.
AirQo's story, now written clear. 🌍

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and directly describes the main change: adding two new documentation files (researchers guide and fair usage policy) to a new data-access docs section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs-data-access

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

JIRA integration encountered authorization issues. Please disconnect and reconnect the integration in the CodeRabbit UI.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Adds a new Data Access documentation section to the Docusaurus docs website, publishing two previously-internal guides (researcher guide + fair usage policy) and wiring them into the docs sidebar configuration.

Changes:

Added docs/data-access/researchers-guide.md (researcher-facing data access and methodology guide).
Added docs/data-access/fair-usage-policy.md (batch download limits, API usage, and fairness principles).
Registered a new dataAccessSidebar autogenerated sidebar in sidebars.ts.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/docs-website/sidebars.ts	Adds an autogenerated sidebar entry for the new `data-access/` docs section.
src/docs-website/docs/data-access/researchers-guide.md	Introduces the researchers’ data access guide with links to API docs and fair usage policy.
src/docs-website/docs/data-access/fair-usage-policy.md	Introduces the fair usage policy doc describing batching limits, workflows, and QC guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+
+---
+
+*This document is prepared by AirQo, Makerere University, Kampala, Uganda. For the latest version, contact [support@airqo.net](mailto:support@airqo.net)*


+
+---
+
+*This document is prepared by AirQo, Makerere University. For the latest information: https://airqo.africa | Contact: [support@airqo.net](mailto:support@airqo.net)*


github-actions · 2026-06-09T19:47:05Z

New azure docs changes available for preview here

…-access guides Replaced all info@airqo.net references with support@airqo.net in both researchers-guide.md and fair-usage-policy.md so the contact email is consistent throughout — support@airqo.net is the inbox monitored by the technical team.

github-actions · 2026-06-09T19:57:25Z

New azure docs changes available for preview here

github-actions · 2026-06-09T19:58:45Z

New azure vertex changes available for preview here

Add researcher guide and fair usage policy as new data-access docs se…

bdaab28

…ction

Baalmart requested a review from Copilot June 9, 2026 19:43

Baalmart added the ready for review label Jun 9, 2026

Copilot started reviewing on behalf of Baalmart June 9, 2026 19:43 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

Baalmart merged commit fe3aab4 into staging Jun 9, 2026
27 checks passed

Baalmart deleted the docs-data-access branch June 9, 2026 20:00

Baalmart mentioned this pull request Jun 9, 2026

move to production #3608

Merged

3 tasks

coderabbitai Bot mentioned this pull request Jun 9, 2026

Add Data Access entry point card to docs homepage product grid #3610

Merged

18 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add researcher guide and fair usage policy as new data-access docs section - #3609

Add researcher guide and fair usage policy as new data-access docs section#3609
Baalmart merged 2 commits into
stagingfrom
docs-data-access

Baalmart commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Estimated Code Review Effort

Poem

Review ran into problems

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		---

		This document is prepared by AirQo, Makerere University, Kampala, Uganda. For the latest version, contact [support@airqo.net](mailto:support@airqo.net)

Uh oh!

Conversation

Baalmart commented Jun 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Pull Request

📋 Description

What does this PR do?

Why is this change needed?

🔗 Related Issues

🔄 Type of Change

🏗️ Affected Services

🧪 Testing

💥 Breaking Changes

📝 Additional Notes

✅ Checklist

Summary by CodeRabbit

Documentation

Uh oh!

coderabbitai Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated Code Review Effort

Poem

Review ran into problems

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Baalmart commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading